|
|
KCUnlock |
||||
| Header: | Keychain.h | Carbon status: | Under Evaluation | |
Unlocks a keychain.
OSStatus KCUnlock (
KCRef keychain,
StringPtr password
);
A reference to the keychain to unlock. Pass NULL to specify the default keychain. If you pass NULL and the default keychain is currently locked, the keychain will appear as the default choice. If you pass a locked keychain, KCUnlock will display the Unlock Keychain dialog box and the keychain will appear as the chosen menu item in keychain popup menu. If the default keychain is currently unlocked, the Unlock Keychain dialog box is not displayed and KCUnlock returns noErr.
A pointer to a Pascal string representing the password string for this keychain. Pass NULL if the user password is unknown. In this case, KCUnlock displays the Unlock Keychain dialog box, and the authentication UI associated with the keychain about to be unlocked. If you specify an invalid password, you will not be able to unlock the keychain with a specified password until the machine is rebooted. In this case, KCUnlock returns errKCInteractionRequired.
A result code. The result code noErr does not guarantee that the specified keychain is unlocked, because the user can select any available keychain and unlock it. The result code errUserCanceled indicates that the user pressed the Cancel button in the Unlock Keychain dialog box. The result code errKCAuthFailed indicates that authentication failed because of too many unsuccessful retries. The result code errKCInteractionRequired indicates that user interaction is required to unlock the keychain. In this case, you will not be able to unlock the keychain with that password until the machine is rebooted.
In most cases, your application does not need to call the KCUnlock function directly, since most Keychain Manager functions requiring an unlocked keychain call KCUnlock automatically. KCUnlock may display the Unlock dialog box if the keychain is currently locked. If your application needs to verify that a keychain is unlocked, call the function KCGetStatus.
The memory that the keychain reference occupies must be released by calling the function KCReleaseKeychain when you are finished with it.
Available beginning with Keychain Manager 1.0. In Keychain Manager 1.0, the kcunlock function provides the same functionality as KCUnlock, except that it accepts a C string rather than Pascal string as an argument. In Keychain 2.0, you should use KCUnlock, since kcunlock is provided for convenience only and may be removed from the header file at some point in the future.
Under evaluation for Carbon. Available in CarbonLib 1.0 and later when KeychainLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by KeychainLib 1.0 and later.
© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)